package edu.java.homework.hw10.stack;

import edu.java.homework.hw10.stack.exceptions.StackEmptyException;

/**
 * Declares the data structure of stack.
 */
public interface Stack {

    /**
     * Pushes new element to the stack.
     * 
     * @param obj
     *            The new element added to the stack.
     */
    void push(Object obj);

    /**
     * Removes the last inserted element from the stack and returns it as
     * result.
     * 
     * @return Returns the last inserted element from the stack removing it.
     */
    Object pop();

    /**
     * Peeks what is the last inserted element in the stack and returns it as
     * result
     * 
     * @return Returns the last inserted element in the stack, without removing
     *         it.
     * 
     * @throws StackEmptyException
     *             Thrown when this method is applied at empty stack.
     */
    Object peek() throws StackEmptyException;

    /**
     * Obtains the number of the elements pushed in the stack.
     * 
     * @return Returns the number of the elements pushed in the stack.
     */
    int size();

    /**
     * Checks whether the stack has elements pushed elements or not.
     * 
     * @return Returns <code>true</code> in case there are no elements, and
     *         <code>false</code> otherwise.
     */
    boolean isEmpty();
}
